 Making Help Files

After creating a bug free program is done, the lone programmer faces another challenge: writing the help file! Writing help files may be as much of a challenge as writing code. For some the .RTF files are harder to read than bit fields! My modest contribution to struggling programmers in the one-man shops is this document template. It brings the creation, compilation and testing of help files all under the Word for Windows roof. Others have created fine templates; this product is no better than theirs. It is suited to the way that I work. Perhaps it will suit you as well!

Making Help Files: An Overview

Setting Up to Make Help Files

The Toolbar

About the Author


Rich Text Format

A format which embeds formatting codes in the text.

.RTF is a pure ASCII file.


Setting Up Shop

Before begin creating help files with this WinWord document template, there are three things you must do first: (1.) Copy some files to the proper directory; (2.) Modify your WIN.INI file and perhaps; (3.) Edit a few macros. The three topics below give you the details!

Help On

Copying Files

Modifying WIN.INI

Modifying Help Macros


Copying Files
Set Up: Copying Files

To insure this document template works, copy the following files to the appropriate directory.

HELP.DOT	in the directory where WinWord looks for .DOT files.

81TBAR.BMP

82TBAR.BMP	All in the same directory as WinWord.

83TBAR.BMP	These bitmaps are for the Toolbar!

84TBAR.BMP

The following files should be in C:\WINWORD\HELP. If you have a different directory structure, you will need to edit a few template macros:

HCP.EXE	-	The Microsoft Help Compiler

SHED.EXE	-	The Hotspot Editor

MAKEHELP.HLP	This help file

HCP.PIF	-	The .PIF file to run HCP in an iconized window

You can download HCP.EXE and SHED.EXE from Lib16 of the WinSDK forum on CompuServe.

See Also

Modifying WIN.INI

Modifying Help Macros


Modifying Help Macros
Set Up: Modifying Help Macros

A couple of macros in HELP.DOT have path statements that you may need to modify so they will work properly with your directory structure. I have Winword installed in C:\WINWORD. My help files, help compiler, .rtf files and SHED are in C:\WINWORD\HELP. If you use this structure you wont need to modify the macros.

BuildHPJ

BuildDefine

HelpCompile

HelpTest

MakeHelp

Shed

Capture

HCP.PIF

See Also

Modifying WIN.INI

Copying Files


SHED.EXE

SHED, the Hotspot Editor enables you to attach

context strings directly to bitmap files. Then, when

the user clicks on a hotspot, WinHelp displays the

topic associated with that context string as either a

new topic or a popup box.

If you dont have a copy, you can download it from

Lib16 of WINSDK on CompuServe.


HCP.EXE

HCP is the Help Compiler for Windows 3.1. If

you dont have a copy, you can download it from

Lib16 of WINSDK on CompuServe.

The Help compiler takes the information contained

in an .RTF file and produces a Windows help file

according to the instructions contained in the project

file.


HCP Pif File

HCP.PIF expects to find the C:\WINWORD\HELP

directory.

This .PIF file runs HCP.BAT, which is created by the

HelpCompile macro. HCP.BAT invokes the Help

compiler, passes the name of the project file as an

argument, and settles down into an iconized state.

For the sake of simplicity you should keep HCP.PIF in

the same directory as HCP.EXE, but you can keep it in

the Windows \SYSTEM directory. If you do, be sure to

edit the .PIF file to set the proper working directory.


HELP.DOT:BuildHPJ Macro

This macro creates and saves the project file to the

C:\WINWORD\HELP directory. Change it to reflect

your directory structure.


HELP.DOT:HelpCompile Macro

This macro, which invokes the help compiler,  expects to find

HCP.EXE and HCP.PIF in C:\WINWORD\HELP. Change it to

reflect your directory structure.


HELP.DOT:HelpTest Macro

This macro, which calls WINHELP.EXE with your help file,

expects to find your help file in C:\WINWORD\HELP. Change

it to reflect your directory structure.


HELP.DOT:MakeHelp Macro

This macro, which calls WINHELP.EXE with this help file

expects to find MAKEHELP.HLP in C:\WINWORD\HELP.

Change it to reflect your directory structure.


HELP.DOT:Shed

This macro expects to find SHED.EXE in C:\WINWORD\HELP

Change it to reflect your directory structure or remove it from the

Toolbar and the Tools menu if you dont have SHED.


HELP.DOT:Capture

This macro loads the Shareware program PaintShop Pro as the

screen capture utility of choice. If you are using HiJaak or some

other product, or if you dont have PaintShop Pro in the C:\PSP

directory, you will need to edit this macro.


HELP.DOT:BuildDefine

This macro builds a header file that defines each Context string

as an integer. Visual Basic programmers need the information in

this file to assign HelpContextID numbers to their screen objects.

This macro expects the project file in the C:\WINWORD\HELP

directory.


Modifying WIN.INI
Set Up: Modify WIN.INI

This document template makes extensive use of the Toolbar to automate the creation of help files. I have modified several of the tool buttons, so you must load the toolbar bitmap if you want your toolbar to look like the one in this help file.

Insert this line into the [MSWord 2.0] section your WIN.INI file:

LoadToolbarBitmaps=1

See Also

Modifying Help Macros

Copying Files


Making Help Files: An Overview

The creation of a help file is a While...Wend loop with three basic steps:

While CreatingHelp

Edit the work file in .RTF format.

Create the Project and MAP files.

Compile and test.

Wend

Help On

Editing the Work File

Inserting Bitmaps

Build Tags

Creating the Project File

The Map File

Compile and Test


Writing the File
Making Help Step #1: Write the File

Help files begin life as text files in .RTF format. If you use a word processor capable of producing .RTF files, all you need to do is use certain character attributes a special footnote symbols to create all of the links, search lists and browse tables.

REMEMBER THESE FEW RULES AND YOU WILL START OFF OKAY

WinHelp displays each help topic one screen at a time.

Each topic must be on its own page in the source file.

Use your word processor to examine the sample file - MAKEHELP.RTF - from which I produced this help file. Notice that this topic is on its own page.

Each help file screen is one topic. Each topic must be on its own page in an .RTF source file.

Character attributes create jumps, popups and context strings.

While you are in the MAKEHELP.RTF, display the hidden text and look at the bordered paragraph above. Note that the first .RTF is single underlined. Single underlining is for  popup links. Note the hidden text immediately after the popup link. Hidden text is for context strings. Finally, notice that the word attributes is double underlined. Double underlined is for jump or topic links.

Examples:

PopupLinkTextContextString	JumpLinkTextContextString

------------------[Hidden Text]	==========[Hidden Text]

It is absolutely essential that no spaces intervene between a prompt text and context string!

Footnotes link jumps and popups with display topics and create titles and keywords.

This may be the hardest part for most people to understand. Probably the best way to figure this out is to browse through MAKEHELP.RTF and see how it uses footnote characters and footnote entries. Here are the important ones:

# is the footnote character used to signify a context string.

K is the footnote character used to signify keywords. Keywords appear in a list box when the user clicks the Search button.

$ is the footnote character used to signify a title. Titles appear in a box when the user clicks on a Keyword in the search box.

Use the Toolbar to create footnotes, links, titles and keywords.

The first screen that appears when your help file is the Index.

The Index is the top of your help file. Its the screen that appears when the user clicks the Contents button in WinHelp.

If you use a different context string - which you are free to do - be sure to declare that context string as the index when you build the project file.

Files must be saved in .RTF format.

The Help compiler cannot use WinWords file format. Save your work in .RTF by clicking the 3rd button on the Toolbar, the diskette icon.

Dont save the file in WinWords .DOC format! I have modified the File menu so that Close does not save! Fear not! If you use the Toolbar, your work is saved in .RTF format!

Dont double-click on the Control menu or use Ctrl+F4 to close the file. If you do so by mistake, answer all prompts about saving your work with No!

If you save your work in WinWord native file format by mistake, open the file and use the File Save As command to save under another name in .RTF format.

Use the Toolbar to save your work in .RTF format. Use the File menu to Close your file.

Now for the step-by-step explanation.

To create a popup box, you would.....

1.	Toggle on the single-underlining.

2.	Type the link text that you want to appear in your help file.

3.	Toggle the single-underlining off  and toggle hidden attribute on.

4.	Type the context string immediately after the link text. No spaces!

5.	Insert a manual page break.

6.	At the top of the next page insert the # footnote character.

7.	In the footnote pane type the context string that you typed in step 4.

8.	Close the footnote pane.

9.	After the # character, type what you want to appear in the popup box.

To create a jump link to a new topic, you would....

Use double-underlining instead of single-underlining in step 3.

To create a Title you would.....

1.	At the top of a new page type insert the # footnote character.

2.	In the footnote pane, type the context string that will link this topic with a popup or a jump link from elsewhere in the help file.

3.	Right next to the # character insert the $ footnote character.

4.	In the footnote pane, type the Title that you want to appear when the user searches the help file.

5.	Close the footnote pane.

6.	Type the topic just the way you want it to appear on the screen.

To create a Keyword you would....

Repeat the steps for creating a title, but insert a K instead of $.

Titles and Keywords must be associated with context strings! Otherwise they will be orphaned and not appear in the help file!

Whew! Thats a long and obtuse explanation. Fortunately, all of this is automated for you by the macros in HELP.DOT. Take a look at the macros bound to the toolbar buttons and you will find that they handle all of this for you!

See Also

The Toolbar

Creating the Project File

Build Tags

The Map File


Build Tags

Build tags allow you to create different versions of a help file and compile conditionally.

A build tag is the footnote character * and a footnote entry that tells the compiler whether or not to include this topic in the .HLP file. For example, this topic might look like this in source code:

# $ K *  Build Tags

and the footnote entries for this topic might look like this:

# BuildTags

$ Build Tags

K Build Tags

* Advanced

If the [BUILD] section of the project file includes the word Advanced, this topic will be included. If the [BUILD] section does not include the word Advanced, this topic will be excluded.

Because you will probably use build tags only rarely, I elected to leave them out of the main footnote dialog box. The last button on the Toolbar can be used to automate the insertion of build tags in your file.

When you create the project file, you will have the option of including these build tags. You can also edit the project file manually to edit the [BUILD] option.

See Also

The Toolbar

Creating the Project File

The Map File


 The Map File

WinHelp uses context strings to find and present topics. Certain applications, such as Visual Basic, can only pass an integer to WinHelp. These integers must be mapped to context strings.

If your application requires the use of HelpContext numbers at design time, this macro will generate a header file that #defines every context string as a unique integer. If you have already built your project file, this macro will also insert the following lines in the project file:

[MAP]

#include <thisfile.h>

This macro requires that only the .RTF file be open when it is run.

This macro only works for help projects which use a single .RTF file. If you want to modify the macro, it is possible to map context strings across multiple files through judicious use of the Window() and WindowName$() functions.


Context Strings

 The most obscure part about writing help files is this notion of a context string. A context string establishes a link between a prompt text (the underlined, words in the help file than invite a click) and a topic (that which appears on its own screen or in a popup box in response to the mouse click). Look at this crude diagram which emulates what you might see when you examine a help files .RTF source code:

{page break}___________________________________________________________________

Some Blather Here

Here is some sampleContextStringSample text. This is how it would appear in the .RTF file, blah, blah, blah... My fellow Americans, blah, blah, blah.

{page break}___________________________________________________________________

# Sample

A small portion, a taste, an example. A free demonstration copy. Etc.

=======================[ FOOTNOTE PANE ]=========================

# ContextStringSample

---------------------------------------------------------------------------------------------------------------

The context string appears in two places. At the front end of the hyperlink it is attached to the prompt text; at the back end it is attached to the topic via a footnote symbol and footnote entry. When the user clicks the word sample, the context string points to the Sample topic which is displayed either as a popup box or separate topic.

If sample were double-underlined and ContextStringSample were hidden, WinHelp would display the Sample topic on its own screen when the user clicked sample. If sample were single-underlined the Sample topic would appear in a popup box.


Creating the Project File
 Making Help Step #2: the Project File

The Microsoft Help Compiler uses a project file which is basically a Make file. The project file, which must have a .hpj extension, tells HCP how to make the help file. Although there are many possible settings, this document template builds only the basic settings. Clicking the HPJ icon on the toolbar presents this dialog box, which accepts values and builds the project file:

The dialog box has hot spots! Click on a control to see what it does!

See Also

The MAP File

Writing the File

Compiling and Testing

Modifying Help Macros


Index

This is the context string of the very first topic in your help file.

When the user clicks the Contents button, WinHelp returns to the

Index. The Index is also the very first topic displayed when a

help file is displayed. You can use anything you want as the

context string for this first topic, but it may be a good idea to use

the word Index as the context string! When you create the project file

the context string must be entered in the Index text box!


Help Window Title

This text box is where you enter the title that you want to appear

in the help window title bar when your help file is used.


Error Log

If you want the Help Compiler to write its error messages to a disk

file, enter the name of that file in this text box. Be sure to follow

correct DOS naming conventions because the macro which builds

your project files does no error checking!


Index

Enter the context string associated with the very first topic in your

help file. This context string is typically ' Index ', but it can be anything.

For example, this help files very first topic, Making Help Files, has the

context string ' Index ' attached to it.


Warning Level

The Help Compiler will warn you of potential problems in your help files

source code. Level 1 gives the fewest warnings, Level 3 the most. I think

you should use Level 3 during development.


Compression

The Help Compiler will compress your files if you check this box. Because

this selection slows compiling significantly, you should avoid selecting this

option until the development cycle is complete.


Files to Include

Enter the names of the .RTF files that contain the source code from which the

help file will be built. You dont have to use the .RTF file extension; the

macro will strip out other extensions - if there are any - and append the .RTF

extension.

Entering the name of a file that is not in Rich Text Rich Text Format will

cause the compiler to abort.

You can use multiple files to build your Windows help file. If you use more than

one file, the file names should be separated by a single space.


Build Tags

Enter the tags for the topics that you want included in this help file.

See Build Tags


Map File

Enter the name of the header file that maps the help files context strings

against integers. See The MAP File


Okay

Once all fields are filled in and selections made, this button begins the compile.


Cancel

This button aborts the compile.


Compile and Test
Making Help Step #3: Compile and Test

Once youve created your help file source code and saved them in .RTF format, simply click the appropriate toolbar buttons to compile and then examine your help file. You can keep the .RTF file open in WinWord while it is being compiled.

 Clicking this icon starts the help compiler in an iconized window.

 Clicking this icon opens the help file you are working on. If you arrange the help file and the .RTF file on screen, you can view and edit your help file simultaneously.

See Also

The Toolbar

Writing the File

Creating the Project File


The Toolbar

The Help Compiler makes extensive use of footnote references to construct the index, the jump table and the browse list. Trouble is, the only footnote characters it recognizes are #, K, $, * and !. It can get pretty confusing, knowing when to insert which symbols where. I have simplified the process by binding the toolbar buttons to macros which automate the work.

The Toolbar buttons have hot spots! Click on a button to see what it does!

See Also

Writing the File

Context Strings


Show Context Strings

Clicking this button opens the disk file that lists the
context strings for your .RTF file.


Build Header File

Clicking this button builds a header file that you need in order
to map integers to the help files context strings. These integers
should be assigned as the values for the HelpContextID property
for your VB objects. Makes it easier to produce context sensitive
help.


Box Red Text

Clicking this button places a box around the paragraph that has
has the caret (insertion point) and makes the text red.


Camera

Opens an dialog box, prompts you for a bitmap file

name and inserts it at the cursor location. See Topic:

Inserting Bitmaps


File New

Opens a new document with HELP.DOT attached.


File Open

The typical WinWord File open macro


File Save

Saves the current file in .RTF format.


Standard Buttons

You probably know what they do!


Toggle Hidden Text

Toggles hidden text off and on.


Display Help

Displays this help file.


Build Project File

Presents a dialog box from which the .HPJ file is made.


Shed

This button runs SHED, the Hotspot Editor.


Compile Help

Compiles the current project into a help file.


Test Help

Opens your help file so you can test it.


Color Auto

Sets the current color to Auto


Color Blue

Sets the current color to blue.


Color Green

Sets the current color to green.

This might look good on some displays.


Color Red

Sets the current color to red.


Color Magenta

Sets the current color to magenta.


Context String

Presents an Input Box into which you type a context string.

The # footnote characters and the context string are automatically

entered in both the topic page and the footnote pane.


Keywords

Presents an Input Box into which you type Keywords that you want

associated with the current topic. The K footnote characters are

entered in both the topic page and the footnote pane. They keywords

are entered in the footnote pane.

Separate Keywords with a semi-colon.


Title

Presents an Input Box into which you type the title of the current topic.

The $ footnote characters and the title are entered in both the topic page

and the footnote pane.


Build Tags

Presents an Input Box into which you type the Build Tag that you want

associated with the current topic. The * footnote characters are entered

in both the topic page and the footnote pane. They keywords are entered

in the footnote pane.

Build tags allow you to keep different versions of your help file and

compile them conditionally. If you use Build Tags you must manually

add a [BUILD TAG] section to the project file.


Inserting Bitmaps

Your help file will be more attractive and more easily understood if it contains bitmaps the represent different windows, dialog boxes, buttons, toolbars, etc. from your application. This document template provides a dialog box that facilitates the insertion of bitmaps into your .RTF files.

By using a screen capture utility such as HiJaak or Paint Shop Pro, you can include every one of your programs visual elements in the help file. With SHED you can create hot spots on these bitmaps that can let your users jump immediatley to appropriate help topics by simply clicking on a screen element with which they are already familiar!

The dialog box has hot spots! Click on a control to see what it does!


Bitmap File Name

Enter the name - including the path - of the bitmap file you

want inserted in the help file. The macro checks to see if the

file exists and warns that it may be be a valid bitmap file if

the extension is not .bmp.


Bitmap Image

Paste the bitmap into the .RTF file at the cursor. Do not use

formats other than .bmp because the Help compiler spits them out!


{bm? Command}

WinWord does not recognize bitmaps that have hotspots created by

SHED. To insert bitmaps with hotspots, you must select this option

instead of the Bitmap Image option. This option is used in conjunction

with the Position options.


Bitmap Left

When you select the {bm? Command} option, selecting this button

will cause the bitmap to be left-aligned in the help file, like this.


Bitmap Right

When you select the {bm? Command} option, selecting this button

will cause the bitmap to be right-aligned in the help file, like this.


Bitmap In Line

When you select the {bm? Command} option, selecting this button

will cause the bitmap to be [image] inserted at the cursor location in the help file..


OK

When you have given all the instructions about this bitmap, this

button fulfills your every wish.


Cancel

This cancels the bitmap operations.


The Footnote Dialog Box

The most time consuming part of creating a help file is inserting the correct footnote characters in the proper order and making sure that youve used the correct character attributes in your document. This dialog box simplifies the creation of popup boxes, jump links and footnote characters.

The dialog box has hot spots! Click on a control to see what it does!

To Create Popup Links

Select

Prompt Text Checkbox

Context String Checkbox

Popup Radio button

Type

The Prompt text in the text box

The Context String in the text box

Click OK

Then, insert a manual page break for the new topic and insert the Context string at the top of the new page. (Instructions on how to insert a context string are in the second paragraph that follows). After you enter the context string, type out the information you want to appear when the help file jumps to or pops up the topic.

To Create Jump Links

Select

Prompt Text Checkbox

Context String Checkbox

Topic Radio button

Type

The Prompt text in the text box

The Context String in the text box

Click OK

Then, insert a manual page break for the new topic and insert the Context string at the top of the new page. (Instructions on how to insert a context string are in the next paragraph). After you enter the context string, type out the information you want to appear when the help file jumps to or pops up the topic.

To Insert Context Strings, Titles and Keywords in Footnotes

Select

Footnote Checkbox

Type

The Context String in the text box

The Title in the text box [optional].

The Keywords in the text box [optional].

Click OK

See Also

Writing the File

Context Strings


Popup

Neat little boxes that pop up onto your screen. Like this one!


Jump Links

A link that takes you to another topic in the help file.

The word attributes is a jump link.


Attributes

Attributes are the characteristics that distinguish the appearance of letters in a font set. The help compiler uses character attributes to build a help files jump table, links and index.

Attribute	Use
Single underline	Creates a popup link.  Single underlined text is used to create a link with a popup box. When you click on the link text, the popup box appears.
Double underline	Creates a jump link. Double underlined text is used to create a link with another topic in the help file. When you click on the link text, you jump to another location in the help file.
Hidden	Creates a context string. Hidden text is used to connect both ends of the link. When you click on a popup link or a jump link the hidden text - which appears immediately after the link text in your .RTF file - tells the help engine where to go!


Prompt Text

Check this box if you want to enter a link text in your help file.

This will insert the prompt text you enter in the text box below

into your help file. The prompt text will be underlined and in

color. The color depends upon whether you are creating a

topic link or a popup link.

The words attributes, popup and jump in this window are prompt text.

You create a popup link or a topic link by selecting the appropriate

radio button at left.


Context String

Check this box if you want to enter a context string. If you are entering

a prompt text, you must also check this box or the help file will not

know where to jump to or which box to pop.

To restate, this check box must be used in conjunction with either the

Prompt Text or Footnotes check boxes. Otherwise, you will simply be

inserting some useless hidden text in your file!


Footnotes

Check this box if you want to insert the footnote characters for a topic,

a popup box, a title or keywords.

If you checked the Context String but not the Prompt Text, then you must

check this box.


Popup Link

Selecting this button causes a popup link to be created. The prompt text

will appear as single-underlined text in your work file.

The words popup and jump in this window are popup links.


Topic Link (aka Jump Link)

Selecting this button causes a topic link to be created. The prompt text

will appear as double-underlined text in your work file.

The word attribute in this help window is a topic link.


Prompt Text

Enter the text that will actually appear in your help file as the prompt text.


Context String

BASICs labels are a helpful metaphor for understanding context strings.

A context string connects a prompt text to a topic. When the user clicks

on a prompt text WinHelp displays the topic to which the context string

points. Definition.


Title

Enter the title that you want attached to the current topic. This will appear

in the top scroll list when the user clicks Search in the help file.


Keywords

Enter the keywords that you want associated with this topic. When the user

clicks on a topic in the Search window of the help file, the keywords are listed

in the box below.

Keywords must be separated by a semi-colon. E.g.:

Compiling;Linking;Debugging


Okay

Click this button to insert the footnote characters and text.


Cancel

This button cancels the process!


 L. E. Brown

Full time pastor, doctoral student, writer of training manuals

 and occasional dabbler in Clipper, Visual Basic, C and C++.

If this help file and the document template were of any use,

drop me a line and let me know. If you have some ideas for

improvements, let me know that, too!

CIS 73277,3615.